Skip to main content

集成构建指南

在将您的集成发布到 Zapier 之前，确保其已充分准备以提供顺畅且高效的用户体验至关重要。以下指南旨在协助您在提交审核前优化集成。遵守这些指南有助于提升集成的功能性和用户互动，并最大化利用 Zapier 来获取新用户，同时通常提升现有客户的全生命周期价值。

熟悉和测试​

熟悉 Zapier​

如果您是 Zapier 新手，请先注册一个免费账户，并尝试使用 热门集成。这有助于您了解 Zapier 的运作方式、用户如何设置 Zap，以及您的集成如何最佳融入 Zap 工作流。

识别关键用例​

关注您应用程序的核心功能。查看 Zapier 应用目录 中的类似集成，以及按应用类别 推荐的功能，以获取灵感，决定集成中应包含哪些元素。同时，向现有客户征求反馈，了解他们对使用您的应用程序进行自动化的需求。

彻底的集成测试​

  • 内部测试：在您的 Zapier 账户中，使用集成的触发器、动作和搜索开发并测试 Zap。确保这些操作无误，并在 Zap 历史记录中成功执行。这让您亲身体验用户将经历的设置过程。
  • 外部测试：与外部用户共享您的集成，以在提交前收集反馈并进行必要调整。

提供演示账户和资源​

提供对功能完整的演示账户的访问，以及必要的资源，以便利审核过程。

自动验证检查​

在构建集成时，参考 集成检查参考文档，确保通过发布提交时的自动验证。发布集成时，所有错误和发布任务必须得到验证，而警告是非强制性的，不会阻止版本推广，但建议审阅以提升可用性。

集成信息​

全面的文档和元数据​

所有集成信息，包括名称、徽标、描述和类别，应完整、准确，并符合 Zapier 的品牌标准。如果您的应用涉及多个类别，请选择最能代表当前主要用例的类别。

澄清非显而易见的特性​

在发布请求说明中详细说明任何复杂特性，并附上相关文档以便理解和审核。

风格和品牌一致性​

Zapier 集成中的术语和特性应与您产品界面中的术语和特性一致。我们致力于为用户提供统一体验，因此您的集成应与 Zapier 中其他流行集成的风格保持一致。请遵守 Zapier 的集成品牌和设计要求，使其融入 Zapier 生态。

身份验证​

简化账户连接​

简化身份验证过程，最好采用 OAuth v2。对于非 OAuth v2 方案，用户应能独立生成并获取 API 密钥或其他凭据，而无需支持团队介入。

帮助文本​

帮助文本应简明、直接且实用。采用 主动语态 以增强清晰度。指导用户查找凭据位置，尤其是非 基本身份验证 时。尽可能使用 Markdown 添加 链接，指向平台相关页面，例如：“在您的 应用名称 仪表板的 API 详情 部分找到 API 密钥。”

平台特定要求​

如果您的平台对 API 访问有特定要求，请将其融入身份验证流程或帮助文本中。例如，如果需要特定计划、API 设置或功能启用，集成应：

  • 告知用户：明确说明先决条件和所需操作。
  • 指导解决：提供说明或链接，帮助用户满足要求，从而避免认证失败并提升体验，同时减少支持需求。

输入格式​

如果身份验证需要特定格式的值（如子域 URL），请在添加输入字段时指定输入格式选项。

处理无效凭据​

针对身份验证问题，返回信息详实且用户友好的错误消息，例如“API 密钥无效”，而非泛化的 401 错误。

触发器​

触发器设计和文案​

触发器文案必须与您产品界面中的术语一致，包括名称、描述、输入字段、帮助文本和输出字段等。例如，Dropbox 使用“文件夹”，Zapier 集成也相应采用。

此外，每个触发器需包括：

  • 描述性、标题大小写的名称，如“New Lead”。
  • 描述性键，如“new_lead”。
  • 描述性名词，反映返回的对象，用于平台消息中自动复数化。
  • 简洁描述，以“Triggers when…”开头，末尾加句号，避免包含集成名称或大写名词。

触发器输入字段​

触发器输入字段 应适当命名，并在必要时添加帮助文本。使用合适的命名、排序和类型，避免 ID 字段复杂化。

  • ID 字段：避免要求用户手动输入 ID；改用 Zapier 的下拉列表。
  • 标签：清晰指示预期数据，避免疑问句形式，使用句子大小写。
  • 帮助文本：简洁实用，仅添加独特信息，使用主动语态和 Markdown。
  • 可选字段：确保空值不引发错误。
  • 字段类型：选择最适合的类型，支持多值功能。
  • 排序：必需字段置顶。

静态 Webhook​

公共集成中不允许静态 Webhook；用户可通过 Zapier Webhook 集成 实现。考虑使用 REST Hooks 以提升体验。

轮询触发器​

轮询触发器 会按计划轮询新数据。为有效实现：

  • 返回结果按创建日期逆序。
  • 返回足够项目（如 100 项），并处理分页和去重。

REST Hook​

REST Hook 触发器 优先采用，支持即时响应。确保多订阅兼容，并匹配轮询数据。

响应内容​

响应应包含关键信息，如 ID、名称和链接，符合 ISO 8601 日期格式，并去除冗余。

样本数据​

提供代表性样本，仅一项目，反映通用键。

输出字段​

自定义标签以澄清缩写、单位或模糊字段。

更新触发器​

避免泛化；提供具体场景触发器。

错误消息​

返回具体、非技术性错误信息。

动作​

动作设计和文案​

动作文案与产品界面一致。

每个动作需包括描述性名称、键、名词和描述。

动作输入字段​

包括必要输入字段，使用动态选项避免 ID 输入。

  • 排序和要求：逻辑排序，平行 API 要求。

响应内容​

返回资源详情，符合格式标准。

样本数据​

代表成功返回的样本。

输出字段​

自定义标签以提升清晰度。

创建或更新功能​

优先使用“搜索或创建”结合“更新”。

删除动作​

谨慎添加，提供替代选项。

错误消息​

返回用户友好错误。

搜索​

查找或创建​

实现“搜索或创建”功能。

搜索设计和文案​

包括描述性名称、键、名词和描述。

搜索输入字段​

适当命名和排序。

响应内容​

返回对象数组，处理无结果情况。

样本数据​

提供代表性样本。

输出字段​

自定义标签。

错误处理​

处理 API 错误，使用适当错误类型。

代码质量​

使用环境变量，保持结构和依赖更新。

结论​

这些指南为成功发布提供框架。请满足发布要求，并联系支持获取帮助。